docs: Added documentation for new reactive future call functionality. by FXschwartz · Pull Request #447 · serverpod/serverpod_docs

FXschwartz · 2026-03-24T13:03:31Z

Here is the documentation covering new reactive future call feature serverpod/serverpod#4882

Copilot

Pull request overview

Adds a new documentation page describing Serverpod’s new “reactive future calls” feature, explaining how to define handlers that react to database table changes and how the underlying outbox/trigger flow works.

Changes:

Introduces a new scheduling concepts doc page for reactive future calls.
Documents where filtering, hasChanged() usage, batching semantics, and runtime trigger management.
Covers operational behavior (polling/scan interval), transaction guarantees, and migration requirements (outbox table).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-24T13:07:17Z

+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));
+  throw Exception('Something went wrong');
+});
+
+// This WILL trigger react — the transaction is committed
+await session.db.transaction((transaction) async {
+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));


Inside session.db.transaction, the example inserts a row without passing the transaction object. In the transactions docs, DB ops must receive transaction: transaction to actually be part of the transaction; otherwise this example may commit independently and would trigger the reactive call, contradicting the comment. Update the insert to include the transaction parameter.

Suggested change

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

throw Exception('Something went wrong');

});

// This WILL trigger react — the transaction is committed

await session.db.transaction((transaction) async {

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

await Trip.db.insertRow(

session,

Trip(status: 'Confirmed'),

transaction: transaction,

);

throw Exception('Something went wrong');

});

// This WILL trigger react — the transaction is committed

await session.db.transaction((transaction) async {

await Trip.db.insertRow(

session,

Trip(status: 'Confirmed'),

transaction: transaction,

);

I'm not sure if we really need this change.

When fact-checking this, I find the suggestion by Copilot to be correct.

Wrapping operations in session.db.transaction((transaction) async { ... }) doesn't automatically enlist them in the transaction.

You have to explicitly opt each database call into the transaction by passing transaction: transaction. Without it, the call runs on its own separate connection and commits immediately. The outer transaction has no hold over it.

Copilot · 2026-03-24T13:07:17Z

+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));
+  throw Exception('Something went wrong');
+});
+
+// This WILL trigger react — the transaction is committed
+await session.db.transaction((transaction) async {
+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));


Same issue in the committed-transaction example: Trip.db.insertRow(...) should receive transaction: transaction to ensure the insert is performed within the transaction being committed (consistent with the Transactions docs) and to make the example behavior correct.

Suggested change

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

throw Exception('Something went wrong');

});

// This WILL trigger react — the transaction is committed

await session.db.transaction((transaction) async {

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

await Trip.db.insertRow(session, Trip(status: 'Confirmed'), transaction: transaction);

throw Exception('Something went wrong');

});

// This WILL trigger react — the transaction is committed

await session.db.transaction((transaction) async {

await Trip.db.insertRow(session, Trip(status: 'Confirmed'), transaction: transaction);

I don't think we need this change either

Same here, we should apply it.

developerjamiu · 2026-06-10T14:29:18Z

+5. Processed entries are deleted from the outbox.
+
+:::info
+The outbox scanner uses the same scan interval as regular future calls, configured via the `futureCall.scanInterval` setting in your YAML configuration.


Suggestion: this names futureCall.scanInterval but doesn't link to the configuration page that documents it. A reader who wants to actually set the value has to navigate the sidebar manually.

Suggested change

The outbox scanner uses the same scan interval as regular future calls, configured via the `futureCall.scanInterval` setting in your YAML configuration.

The outbox scanner uses the same scan interval as regular future calls, configured via the `futureCall.scanInterval` setting in your YAML configuration. See [Configuration](configuration) for the full set of future-call options.

Swiftaxe

Some comments added. Mainly about leaving out implementation details and skipping to what is essential for the user to know.

Swiftaxe · 2026-06-10T13:48:44Z

@@ -0,0 +1,131 @@
+# Reactive Future Calls


We have started adding frontmatter description to all pages for SEO.
Also, use sentence case for headings.

Suggested change

# Reactive Future Calls

---

description: React to database row changes in near real-time using Serverpod's reactive future calls, which trigger your handler when inserts, updates, or deletes match a condition.

---

# Reactive future calls

Swiftaxe · 2026-06-10T13:50:58Z

+After creating your reactive future call class, run code generation:
+
+```bash
+$ serverpod generate


We will update this to match the new serverpod start workflow in a different PR.

Swiftaxe · 2026-06-10T14:04:11Z

+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));
+  throw Exception('Something went wrong');
+});
+
+// This WILL trigger react — the transaction is committed
+await session.db.transaction((transaction) async {
+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));


When fact-checking this, I find the suggestion by Copilot to be correct.

Wrapping operations in session.db.transaction((transaction) async { ... }) doesn't automatically enlist them in the transaction.

You have to explicitly opt each database call into the transaction by passing transaction: transaction. Without it, the call runs on its own separate connection and commits immediately. The outer transaction has no hold over it.

Swiftaxe · 2026-06-10T14:04:32Z

+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));
+  throw Exception('Something went wrong');
+});
+
+// This WILL trigger react — the transaction is committed
+await session.db.transaction((transaction) async {
+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));


Same here, we should apply it.

Swiftaxe · 2026-06-10T14:10:10Z

+
+Reactive future calls let you react to database changes in near real-time. When a row is inserted, updated, or deleted, Serverpod can automatically and asynchronously invoke your code with the changed data. This is useful for scenarios like sending notifications when an order is confirmed, syncing data to external systems, or triggering workflows based on state changes.
+
+Under the hood, reactive future calls use PostgreSQL triggers and an outbox pattern. A database trigger fires within the same transaction as the data change, writing an entry to an outbox table. Serverpod periodically polls the outbox on a configurable scan interval and dispatches matching entries to your handler. Because the trigger runs in the same transaction, rolled-back changes never produce events.


The users don't need to know how things work under the hood. What they need to know here is that the rolled-back changes never produce events. We can skip directly to the point.

Suggested change

Under the hood, reactive future calls use PostgreSQL triggers and an outbox pattern. A database trigger fires within the same transaction as the data change, writing an entry to an outbox table. Serverpod periodically polls the outbox on a configurable scan interval and dispatches matching entries to your handler. Because the trigger runs in the same transaction, rolled-back changes never produce events.

Because the trigger runs in the same transaction, rolled-back changes never produce events.

Swiftaxe · 2026-06-10T14:16:44Z

+
+Your reactive future calls are automatically discovered and registered alongside regular future calls. No manual registration is needed.
+
+## How it works


There are many technical details here that the user probably does not need to concern themselves with.

Consider just saying something like for the whole ## How it works section:

How it works

Reactive future calls use a scan interval. The same interval as regular future calls, configured via futureCall.scanInterval. Serverpod polls for new entries at this interval, so handlers fire in near real-time, rather than instantly.

Rows that accumulate between scans are batched together and delivered to react in a single call. This is why react receives a List rather than a single object.

Swiftaxe · 2026-06-10T14:29:59Z

+}
+```
+
+The `where` getter defines a condition that becomes a `WHEN` clause on the PostgreSQL trigger. Only changes matching this condition will create outbox entries. In the example above, the trigger only fires when the `status` column equals `'Confirmed'`.


Mentioning 'outbox' is an implementation details of no concern to our users.

Could we boil these two paragraphs down to the essentials? Perhaps something like:

The react method is your handler. It's called with every row that matches the condition. The where getter filters which changes reach the handler.

developerjamiu · 2026-06-10T14:33:16Z

+
+## Transaction safety
+
+Because the trigger runs inside the same database transaction as the data change, reactive future calls have transactional guarantees:


Suggestion: this section talks about transaction commit/rollback semantics without linking to the transactions docs. A reader unfamiliar with session.db.transaction has to find it themselves.

Suggested change

Because the trigger runs inside the same database transaction as the data change, reactive future calls have transactional guarantees:

Because the trigger runs inside the same database transaction as the data change, reactive future calls have transactional guarantees (see [Transactions](../database/transactions) for the underlying API):

developerjamiu · 2026-06-10T14:35:40Z

+// This will NOT trigger react — the transaction is rolled back
+await session.db.transaction((transaction) async {
+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));
+  throw Exception('Something went wrong');
+});
+
+// This WILL trigger react — the transaction is committed
+await session.db.transaction((transaction) async {
+  await Trip.db.insertRow(session, Trip(status: 'Confirmed'));
+});


Nit: em-dashes in code comments. The style guide discourages them in running text, and comments read as prose to the reader. Swap for periods or colons.

Suggested change

// This will NOT trigger react — the transaction is rolled back

await session.db.transaction((transaction) async {

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

throw Exception('Something went wrong');

});

// This WILL trigger react — the transaction is committed

await session.db.transaction((transaction) async {

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

});

// This will NOT trigger react. The transaction is rolled back.

await session.db.transaction((transaction) async {

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

throw Exception('Something went wrong');

});

// This WILL trigger react. The transaction is committed.

await session.db.transaction((transaction) async {

await Trip.db.insertRow(session, Trip(status: 'Confirmed'));

});

Added documentation for new reactive future call functionality.

762c8c1

Copilot AI review requested due to automatic review settings March 24, 2026 13:03

Copilot started reviewing on behalf of FXschwartz March 24, 2026 13:04 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Addressed copilot suggestions.

f471528

developerjamiu reviewed Jun 10, 2026

View reviewed changes

Swiftaxe reviewed Jun 10, 2026

View reviewed changes

developerjamiu reviewed Jun 10, 2026

View reviewed changes

developerjamiu assigned FXschwartz Jun 10, 2026

developerjamiu added the documentation Improvements or additions to documentation label Jun 10, 2026

	The outbox scanner uses the same scan interval as regular future calls, configured via the `futureCall.scanInterval` setting in your YAML configuration.
	The outbox scanner uses the same scan interval as regular future calls, configured via the `futureCall.scanInterval` setting in your YAML configuration. See [Configuration](configuration) for the full set of future-call options.

-# Reactive Future Calls
+---
+description: React to database row changes in near real-time using Serverpod's reactive future calls, which trigger your handler when inserts, updates, or deletes match a condition.
+---
+# Reactive future calls


		Reactive future calls let you react to database changes in near real-time. When a row is inserted, updated, or deleted, Serverpod can automatically and asynchronously invoke your code with the changed data. This is useful for scenarios like sending notifications when an order is confirmed, syncing data to external systems, or triggering workflows based on state changes.

		Under the hood, reactive future calls use PostgreSQL triggers and an outbox pattern. A database trigger fires within the same transaction as the data change, writing an entry to an outbox table. Serverpod periodically polls the outbox on a configurable scan interval and dispatches matching entries to your handler. Because the trigger runs in the same transaction, rolled-back changes never produce events.


		Your reactive future calls are automatically discovered and registered alongside regular future calls. No manual registration is needed.

		## How it works


		## Transaction safety

		Because the trigger runs inside the same database transaction as the data change, reactive future calls have transactional guarantees:

Conversation

FXschwartz commented Mar 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Swiftaxe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

How it works

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants